home *** CD-ROM | disk | FTP | other *** search
/ Mission 3 / Mission 3.zip / Mission 3.iso / demovers / arthur / module / develop.txt
Text File  |  1998-06-09  |  12KB  |  336 lines
  1.  
  2.  
  3.  
  4.   Suchmodule für Arthur ab Version 1.8
  5.   Suchmodul-Formatbeschreibung
  6.  
  7.  
  8.  
  9. +---------------------------------------+----------------------------------------+
  10.  
  11. Ab Arthur 1.8 ist es ja nun möglich auch eigene Suchmodule einzubinden.
  12. Um dem geneigten Programmierer das Format der Module näher zu bringen, 
  13. soll dieser Text dienen.
  14.  
  15. Möglich wäre dann beispielsweise auch eine Nummernbibliothek mit dem zugehörigen
  16. Suchmodul. Das Bibliotheksformat bietet hierfür die Möglichkeit an, ein bestimmtes 
  17. namentliches Suchmodul vorzugsweise zu verwenden.
  18.  
  19. Übrigens:
  20. Wer ein Modul schreibt, daß mit intelligenter und lokaler Suche um 
  21. einiges schneller ist als die in Arthur eingebauten und es dem Arthur-Paket
  22. zur Verfügung stellt, bekommt Arthur für die Versandkosten =:)
  23.  
  24.  
  25. +---------------------------------------+----------------------------------------+
  26.  
  27.  
  28. Der Text ist in folgende Kapitel gegliedert:
  29.  
  30.  
  31.  1.0 · Richtlinien/Hinweise zum Modul
  32.  2.0 · Der Modul-Header
  33.  3.0 · Aufbau der Modul-Infostruktur
  34.  4.0 · Fehlercodes
  35.  5.0 · Übergabeparameter über den Stack
  36.  6.0 · Übergabe im Assembler-"Header"
  37.  7.0 · Vorhandene, anspringbare Routinen von Arthur
  38.  8.0 · Arthur-Bibliotheks-Format V1.8
  39.  
  40.  
  41.  
  42.  
  43.  
  44. +---------------------------------------+----------------------------------------+
  45. 1.0:  Modulhinweise:
  46. +---------------------------------------+----------------------------------------+
  47.    ~ Parameter werden nach Wunsch von Arthur über den Stack
  48.      oder über einen ASM-Header übergeben.
  49.    ~ Die Register werden von Arthur komplett gerettet.
  50.    ~ modale Dialogboxen, Zeichenfunktionen erlaubt (über-
  51.      gebenes VDI-Handle verwenden)
  52.    ~ Speicheranforderungen erlaubt, müssen aber vor Ende
  53.      freigegeben werden.
  54.    ~ Rücksprung nur mit rts.
  55.      (Das Modul wird als ein Unterprogramm von Arthur betrachtet.)
  56.    ~ die geladene Bibliothek ist auf Kompatibilität geprüft.
  57.    ~ die Buchstaben eines übergebenen Suchstrings sind bei 
  58.      Option "Groß/Klein egal" schon alle Groß.
  59.    ~ maximal 256 Ergebnisse
  60.  
  61.    ~ Hinweise zu den Rückgabeparametern (in D0): 
  62.  
  63.     · Anzahl Ergebnisse, wenn Suche erfolgreich.
  64.     · Bei einem Fehler sollte das Modul in D0 einen Zeiger auf 
  65.       einen nullterminierten Alertstring oder einen Fehlercode kleiner 0
  66.       (siehe Fehlercodes) zurückliefern. 
  67.     · Der Rückgabewert Null besagt, daß das Gesuchte nicht gefunden wurde.
  68.     · Anzahl durchsuchter Bibliothekseinträge als Long ab Buffer schreiben. 
  69.  
  70.  
  71.  
  72.    ~ Die Bibliotheksdaten dürfen natürlich nicht verändert werden.
  73.  
  74.  
  75.  
  76.  
  77.  
  78. +---------------------------------------+----------------------------------------+
  79. 2.0: Der Modul-Header
  80. +---------------------------------------+----------------------------------------+
  81.  
  82.   Der Modul-Header, der vor das Assemblierte Modul
  83.   gelinkt werden muss (64 Byte Länge):  
  84.   ================================================
  85.  Offset        Format        Wert    Beschreibung        
  86.  ------------------------------------------------------------    
  87.      00        Long        'AMOD'    Identifikation
  88.      04        Long        $0        reserviert        
  89.      08        Long        $0        reserviert        
  90.      12        Long        $FF2253    fest        
  91.      16        Long        ?         Branch auf eine Struktur zur
  92.                                      Modulinformation (Autor, Version..)        
  93.                                      oder Null.
  94.      20        Long        ?         Branch auf Suchroutine 
  95.                                      oder Null (dann nimmt Arthur die Adresse
  96.                                      des geladenen Moduls + Header als 
  97.                                      Unterprogrammadresse an).
  98.      24        Long        'V1.0'    Modulversion        
  99.      28        Word        ?         Bitvektor:
  100.  
  101.                      Bit        Beschreibung
  102.                      --------------------
  103.                      0        gesetzt = Modul Speicherresistent
  104.                      1        gesetzt = Werte über ASM-Header
  105.                                         (siehe ASM-Header)
  106.                      2        gesetzt = wind_update() setzen
  107.                      3        gesetzt = beg_update() setzen
  108.                      4        gesetzt = Maus auf "Busy" setzen.
  109.                               (kann aber auch das Modul machen).
  110.                      5-15     reserviert
  111.  
  112.      30-45    Byte        ?        gewünschter Popuptext (Nullterminiert)
  113.      46-63    Byte        ?        freier Text (Nullterminiert)
  114.  
  115.     Ggf. ist Nichtverwendetes mit Wert Null zu füllen.
  116.  
  117.  
  118.  
  119.  
  120.  
  121. +---------------------------------------+----------------------------------------+ 
  122. 3.0:  Modul-Infostruktur: 
  123. +---------------------------------------+----------------------------------------+
  124.  
  125.   Die Modul-Infostruktur dient zur Ausgabe einer Info über das Modul (Autor,
  126.   Modulversion etc.).
  127.   
  128.   Die Modul-Info wird aufgerufen, wenn ein Anwender im Popup-Menü einen
  129.   Eintrag mit Shift anwählt.
  130.  
  131.   Die Info kann sein:
  132.  
  133.     · Ein nullterminierter Alertstring, der dann von Arthur als Alert im Fenster  
  134.       dargestellt wird,
  135.     · oder etwas Eigenes (modal).
  136.  
  137.   Der Strukturaufbau als Alert:
  138.   -----------------------------
  139.   infostrukt:      dc.l -1        ; Alertstring
  140.                    dc.b '[1][Beispielinfo eines|Arthur-Suchmoduls][  OK  ],0
  141.  
  142.   Der Strukturaufbau bei Eigener Infodarstellung:
  143.   -----------------------------------------------
  144.   infostrukt:      dc.l infofunc  ; Branch auf Info-Routine (rts verwenden!)
  145.   (Die Register werden von Arthur gerettet)
  146.  
  147.  
  148.  
  149. +---------------------------------------+----------------------------------------+ 
  150. 4.0:  Fehlercodes: 
  151. +---------------------------------------+----------------------------------------+
  152.  
  153.       -39    nicht genügend Speicher
  154.      -107    fehlerhafte Bibliotheksdaten
  155.      -109    fehlerhafte Parameter
  156.      -110    fehlerhafte Bibliotheksadresse
  157.      -111    fehlerhafte Suchstringadresse
  158.      -112    fehlerhafte Bibliothek
  159.      -113    falsches Bibliotheksformat
  160.      -114    keine Grafikausgaben möglich
  161.      -115    unbekannter Fehler
  162.      -116    Suche nicht möglich
  163.  
  164.  
  165.  
  166. +---------------------------------------+----------------------------------------+
  167. 5.0:  Übergabeparameter:
  168. +---------------------------------------+----------------------------------------+
  169.  
  170.    Stackpos    Format    Beschreibung 
  171.    ------------------------------------------------------------
  172.      00    Long    Rücksprungadresse                
  173.      04    Word    ap_id von Arthur
  174.      06    Word    Arthur-VDI-Handle
  175.      08    Word    Bitvektor der Arthur-Suchoptionen:
  176.  
  177.                    Bit    Bedeutung
  178.                    -----------------
  179.                    0    Gross/Klein egal
  180.                    1    intelligente Suche
  181.                    2    Suchbeschränkung aktiv
  182.                    (im High-Byte steht dann die max. Ergebnisanzahl)
  183.  
  184.      10    Long    Adresse Arthur-Basepage
  185.      14    Long    Adresse Bibliothek
  186.      18    Long    Adresse eines 512 Bytes großen, frei nutzbaren Buffers ab 
  187.                    dessen Anfang der Suchstring steht.
  188.      22    Word    Länge des Suchstrings     
  189.      24    Long    Adresse Ergebnispointerspeicher (256 * 4 Longs)
  190.      28    Long    Adresse der Decodier-Routine (siehe decode-Aufruf)
  191.      32    Long    Adresse der String-Exist-Routine (siehe string_exist-Aufruf)
  192.      36    Long    Adresse der Upper-Routine (siehe upper-Aufruf)
  193.  
  194.  
  195.  
  196.  
  197.  
  198. +---------------------------------------+----------------------------------------+ 
  199. 6.0:  Übergabe über einen Assembler-"Header":
  200. +---------------------------------------+----------------------------------------+
  201.      Wie übergabeparameter, nur ID 'ASMP' ersetzt die Rücksprungadresse.
  202.      Auf dem Stack steht dann nur die Rücksprungadresse.
  203.  
  204.      Sinn dieser Möglichkeit ist die Übergabe der Parameter in schon
  205.      festgelegte Variablen, die am Anfang des Programmes deklariert sind
  206.      (z.Bsp. mit EQU). Die Parameter werden dann nicht über den Stack 
  207.      übergeben, sondern einfach in das Modul geschrieben (sofern im Header
  208.      das Bit zum einschalten dieser Funktion gesetzt ist).
  209.  
  210. Zum Beispiel:
  211.  
  212.  
  213. id:                 dc.l    'ASMP'
  214. arthur_ap_id:       dc.w    0
  215. vdi_handle:         dc.w    0
  216. bitvec:             dc.w    0
  217. arthur_basepage:    dc.l    0
  218. library:            dc.l    0
  219. buffer:             dc.l    0
  220. search_strlen:      dc.w    0
  221. erg_pointermem:     dc.l    0
  222. decode_adr:         dc.l    0
  223. string_exist_adr:   dc.l    0     
  224. upper_adr:          dc.l    0
  225.  
  226. Werte mit Null belegen, Arthur schreibt dann, wie schon erwähnt, dort 
  227. die Parameter hinein.
  228.  
  229.  
  230.  
  231.  
  232.  
  233. +---------------------------------------+----------------------------------------+    
  234. 7.0:  Vorhandene, anspringbare Routinen von Arthur:
  235. +---------------------------------------+----------------------------------------+
  236.  
  237. Die nun folgenden Routinen sind Arthur-Routinen, die vom Modul angesprungen werden 
  238. können bzw. müssen (bei decode notwendig).
  239.  
  240.  
  241. decode: Routine zum decodieren eines Eintragstextes. 
  242. -------
  243.     Aufruf:
  244.  
  245.     move.l    stradr,-(sp)    ; Stringadresse auf den Stack    
  246.     move.w    strlen,-(sp)    ; Stringlänge auf den Stack
  247.     jsr        decode            ; anspringen
  248.     lea        6(sp),sp        ; Stack restaurieren
  249.  
  250. Rückgabewert: keiner
  251.     
  252. Das Unterprogramm verändert die Register D0, D1 und A1 und beendet 
  253. sich mittels rts. Die Routine prüft auf Stringlänge Null.
  254.  
  255.  
  256. upper: Wandeln eines Strings von Klein nach Groß
  257. ------
  258.     Aufruf:
  259.     
  260.     move.l    stradr,-(sp)    ; Stringadr. auf den Stack
  261.     move.w    strlen,-(sp)    ; Stringlänge auf den Stack
  262.     jsr        upper            ; anspringen
  263.     lea        6(sp),sp        ; Stack restaurieren
  264.  
  265. Rückgabewert: keiner
  266.  
  267. Das Unterprogramm verändert die Register D0, D1 und A1 und beendet 
  268. sich mittels rts. Die Routine prüft auf Stringlänge Null.
  269.  
  270.  
  271. string_exist: prüfen auf Vorhandensein eines Strings in einem anderen
  272. -------------
  273.     Aufruf:
  274.     
  275.     move.l    stradr1,-(sp)    ; Stringadr. auf den Stack
  276.     move.l    stradr2,-(sp)    ; Stringadr. auf den Stack (gesuchter String)
  277.     move.w    strlen1,-(sp)    ; Stringlänge auf den Stack
  278.     move.w    strlen2,-(sp)    ; Stringlänge auf den Stack (gesuchter String)
  279.     jsr        string_exist    ; anspringen
  280.     lea        12(sp),sp        ; Stack restaurieren
  281.  
  282. Rückgabewert: 0 = nicht gefunden, -1 = gefunden
  283.  
  284. Das Unterprogramm verändert die Register D0-D3, A0 und A1 und beendet 
  285. sich mittels rts. Die Routine prüft auf Stringlänge Null. Beide
  286. Strings können unterschiedlich groß und der Suchstring kann auch größer
  287. als der Quellstring sein.
  288.  
  289.  
  290.  
  291.  
  292.  
  293. +---------------------------------------+----------------------------------------+
  294. 8.0:  Arthur-Bibliotheksformat V1.8:
  295. +---------------------------------------+----------------------------------------+
  296.  
  297. Offset       Länge(in Byte)   Beschreibung
  298. --------------------------------------------------------------------------------
  299. 0            14               Identifikation 'ArthurLIB V1.8'
  300. 14-24        max. 10          (Optional)Popup-Name des vorzugsweise zu 
  301.                               verwendenden Suchmoduls. Rest ist mit Nullbytes zu 
  302.                               füllen.
  303. 25-31        6                Reserviert, mit Nullbytes zu füllen
  304.  
  305.  
  306. dann die Bibliotheks-Gesamteinträge:
  307. ------------------------------------
  308.  
  309. Format       Beschreibung
  310. -------------------------------------------------------------------------------
  311. Byte         Länge des gesamten Eintrages (dieses Längenbyte ausgenommen)
  312. Byte         Länge des Eintrages
  313. ...          der codierte Eintrag
  314. Byte         Länge der Übersetzung des Bibliotheks-Eintrages
  315. ...          die codierte Übersetzung
  316. Byte         Nullbyte
  317.  
  318. ...und so weiter, bis die Länge des Gesamteintrages Null ist:
  319.  
  320. Long         Bibliotheksende (Null)
  321. +---------------------------------------+----------------------------------------+
  322.  
  323. Das wars, viel Erfolg!
  324. Vorschläge zur Modulschnittstelle nehme ich gerne entgegen.
  325.  
  326.  
  327. 09.06.1998
  328. Arthur-Modulschnittstelle V1.0
  329. Richard Gordon Faika
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.